{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "library(IRdisplay)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The IRkernel already displays things automatically, but the [`IRdisplay` package](http://irkernel.github.io/docs/IRdisplay/0.4.4/) allows to programmatically access this machinery.\n",
    "\n",
    "You can display all standard formats of an object via [`display`](http://irkernel.github.io/docs/IRdisplay/0.4.4/display.html). This uses [`repr_*`](http://irkernel.github.io/docs/repr/0.8/repr-generics.html) and the [`jupyter.display_mimetypes` option](http://irkernel.github.io/docs/IRdisplay/0.4.4/IRdisplay-options.html):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<strong>$jupyter.display_mimetypes</strong> = <ol class=list-inline>\n",
       "\t<li>'text/plain'</li>\n",
       "\t<li>'text/html'</li>\n",
       "\t<li>'text/markdown'</li>\n",
       "\t<li>'text/latex'</li>\n",
       "\t<li>'application/json'</li>\n",
       "\t<li>'application/javascript'</li>\n",
       "\t<li>'application/pdf'</li>\n",
       "\t<li>'image/png'</li>\n",
       "\t<li>'image/jpeg'</li>\n",
       "\t<li>'image/svg+xml'</li>\n",
       "</ol>\n"
      ],
      "text/latex": [
       "\\textbf{\\$jupyter.display\\_mimetypes} = \\begin{enumerate*}\n",
       "\\item 'text/plain'\n",
       "\\item 'text/html'\n",
       "\\item 'text/markdown'\n",
       "\\item 'text/latex'\n",
       "\\item 'application/json'\n",
       "\\item 'application/javascript'\n",
       "\\item 'application/pdf'\n",
       "\\item 'image/png'\n",
       "\\item 'image/jpeg'\n",
       "\\item 'image/svg+xml'\n",
       "\\end{enumerate*}\n"
      ],
      "text/markdown": [
       "**$jupyter.display_mimetypes** = 1. 'text/plain'\n",
       "2. 'text/html'\n",
       "3. 'text/markdown'\n",
       "4. 'text/latex'\n",
       "5. 'application/json'\n",
       "6. 'application/javascript'\n",
       "7. 'application/pdf'\n",
       "8. 'image/png'\n",
       "9. 'image/jpeg'\n",
       "10. 'image/svg+xml'\n",
       "\n",
       "\n"
      ],
      "text/plain": [
       "$jupyter.display_mimetypes\n",
       " [1] \"text/plain\"             \"text/html\"              \"text/markdown\"         \n",
       " [4] \"text/latex\"             \"application/json\"       \"application/javascript\"\n",
       " [7] \"application/pdf\"        \"image/png\"              \"image/jpeg\"            \n",
       "[10] \"image/svg+xml\"         \n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "options('jupyter.display_mimetypes')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false,
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "\n",
       "<table width=\"100%\" summary=\"page for display {IRdisplay}\"><tr><td>display {IRdisplay}</td><td style=\"text-align: right;\">R Documentation</td></tr></table>\n",
       "\n",
       "<h2>Create and use multiple available reprs</h2>\n",
       "\n",
       "<h3>Description</h3>\n",
       "\n",
       "<p>Both functions create a mimebundle for multiple reprs.\n",
       "<code>display</code> proceeds to publish it using <code>publish_mimebundle</code>.\n",
       "<code>prepare_mimebundle</code> returns it (see <em>Value</em> for details)\n",
       "</p>\n",
       "\n",
       "\n",
       "<h3>Usage</h3>\n",
       "\n",
       "<pre>\n",
       "display(obj)\n",
       "\n",
       "prepare_mimebundle(obj, mimetypes = getOption(\"jupyter.display_mimetypes\"),\n",
       "  metadata = NULL, error_handler = stop)\n",
       "</pre>\n",
       "\n",
       "\n",
       "<h3>Arguments</h3>\n",
       "\n",
       "<table summary=\"R argblock\">\n",
       "<tr valign=\"top\"><td><code>obj</code></td>\n",
       "<td>\n",
       "<p>The object to create representations for</p>\n",
       "</td></tr>\n",
       "<tr valign=\"top\"><td><code>mimetypes</code></td>\n",
       "<td>\n",
       "<p>Mimetypes to create reprs for. The defaults are defined by the option <code>jupyter.display_mimetypes</code>. (see: IRdisplay-options)</p>\n",
       "</td></tr>\n",
       "<tr valign=\"top\"><td><code>metadata</code></td>\n",
       "<td>\n",
       "<p>Metadata to attach to the result (can be expanded by additional metadata)</p>\n",
       "</td></tr>\n",
       "<tr valign=\"top\"><td><code>error_handler</code></td>\n",
       "<td>\n",
       "<p>Function used when errors in individual reprs occur</p>\n",
       "</td></tr>\n",
       "</table>\n",
       "\n",
       "\n",
       "<h3>Value</h3>\n",
       "\n",
       "<p><code>prepare_mimebundle</code> returns a list with items corresponding to the parameters of <code>publish_mimebundle</code> (<code>data</code> and <code>metadata</code>)\n",
       "</p>\n",
       "\n",
       "\n",
       "<h3>See Also</h3>\n",
       "\n",
       "<p><code>publish_mimebundle</code>\n",
       "</p>\n",
       "\n",
       "\n",
       "<h3>Examples</h3>\n",
       "\n",
       "<pre>\n",
       "dev.new(); plot(sqrt); p &lt;- recordPlot(); dev.off()\n",
       "bundle &lt;- prepare_mimebundle(p)\n",
       "\n",
       "## Not run: ## (Run inside of an IRkernel)\n",
       "display(help(display))\n",
       "## End(Not run)\n",
       "\n",
       "</pre>\n",
       "\n",
       "<hr /><div style=\"text-align: center;\">[Package <em>IRdisplay</em> version 0.4.4 ]</div>"
      ],
      "text/latex": [
       "\\inputencoding{utf8}\n",
       "\\HeaderA{display}{Create and use multiple available reprs}{display}\n",
       "\\aliasA{prepare\\_mimebundle}{display}{prepare.Rul.mimebundle}\n",
       "%\n",
       "\\begin{Description}\\relax\n",
       "Both functions create a mimebundle for multiple reprs.\n",
       "\\code{display} proceeds to publish it using \\code{\\LinkA{publish\\_mimebundle}{publish.Rul.mimebundle}}.\n",
       "\\code{prepare\\_mimebundle} returns it (see \\emph{Value} for details)\n",
       "\\end{Description}\n",
       "%\n",
       "\\begin{Usage}\n",
       "\\begin{verbatim}\n",
       "display(obj)\n",
       "\n",
       "prepare_mimebundle(obj, mimetypes = getOption(\"jupyter.display_mimetypes\"),\n",
       "  metadata = NULL, error_handler = stop)\n",
       "\\end{verbatim}\n",
       "\\end{Usage}\n",
       "%\n",
       "\\begin{Arguments}\n",
       "\\begin{ldescription}\n",
       "\\item[\\code{obj}] The object to create representations for\n",
       "\n",
       "\\item[\\code{mimetypes}] Mimetypes to create reprs for. The defaults are defined by the option \\code{jupyter.display\\_mimetypes}. (see: \\LinkA{IRdisplay-options}{IRdisplay.Rdash.options})\n",
       "\n",
       "\\item[\\code{metadata}] Metadata to attach to the result (can be expanded by additional metadata)\n",
       "\n",
       "\\item[\\code{error\\_handler}] Function used when errors in individual reprs occur\n",
       "\\end{ldescription}\n",
       "\\end{Arguments}\n",
       "%\n",
       "\\begin{Value}\n",
       "\\code{prepare\\_mimebundle} returns a list with items corresponding to the parameters of \\code{\\LinkA{publish\\_mimebundle}{publish.Rul.mimebundle}} (\\code{data} and \\code{metadata})\n",
       "\\end{Value}\n",
       "%\n",
       "\\begin{SeeAlso}\\relax\n",
       "\\code{\\LinkA{publish\\_mimebundle}{publish.Rul.mimebundle}}\n",
       "\\end{SeeAlso}\n",
       "%\n",
       "\\begin{Examples}\n",
       "\\begin{ExampleCode}\n",
       "dev.new(); plot(sqrt); p <- recordPlot(); dev.off()\n",
       "bundle <- prepare_mimebundle(p)\n",
       "\n",
       "## Not run: ## (Run inside of an IRkernel)\n",
       "display(help(display))\n",
       "## End(Not run)\n",
       "\n",
       "\\end{ExampleCode}\n",
       "\\end{Examples}"
      ],
      "text/plain": [
       "display               package:IRdisplay                R Documentation\n",
       "\n",
       "_\bC_\br_\be_\ba_\bt_\be _\ba_\bn_\bd _\bu_\bs_\be _\bm_\bu_\bl_\bt_\bi_\bp_\bl_\be _\ba_\bv_\ba_\bi_\bl_\ba_\bb_\bl_\be _\br_\be_\bp_\br_\bs\n",
       "\n",
       "_\bD_\be_\bs_\bc_\br_\bi_\bp_\bt_\bi_\bo_\bn:\n",
       "\n",
       "     Both functions create a mimebundle for multiple reprs. ‘display’\n",
       "     proceeds to publish it using ‘publish_mimebundle’.\n",
       "     ‘prepare_mimebundle’ returns it (see _Value_ for details)\n",
       "\n",
       "_\bU_\bs_\ba_\bg_\be:\n",
       "\n",
       "     display(obj)\n",
       "     \n",
       "     prepare_mimebundle(obj, mimetypes = getOption(\"jupyter.display_mimetypes\"),\n",
       "       metadata = NULL, error_handler = stop)\n",
       "     \n",
       "_\bA_\br_\bg_\bu_\bm_\be_\bn_\bt_\bs:\n",
       "\n",
       "     obj: The object to create representations for\n",
       "\n",
       "mimetypes: Mimetypes to create reprs for. The defaults are defined by\n",
       "          the option ‘jupyter.display_mimetypes’. (see:\n",
       "          IRdisplay-options)\n",
       "\n",
       "metadata: Metadata to attach to the result (can be expanded by\n",
       "          additional metadata)\n",
       "\n",
       "error_handler: Function used when errors in individual reprs occur\n",
       "\n",
       "_\bV_\ba_\bl_\bu_\be:\n",
       "\n",
       "     ‘prepare_mimebundle’ returns a list with items corresponding to\n",
       "     the parameters of ‘publish_mimebundle’ (‘data’ and ‘metadata’)\n",
       "\n",
       "_\bS_\be_\be _\bA_\bl_\bs_\bo:\n",
       "\n",
       "     ‘publish_mimebundle’\n",
       "\n",
       "_\bE_\bx_\ba_\bm_\bp_\bl_\be_\bs:\n",
       "\n",
       "     dev.new(); plot(sqrt); p <- recordPlot(); dev.off()\n",
       "     bundle <- prepare_mimebundle(p)\n",
       "     \n",
       "     ## Not run:\n",
       "     ## (Run inside of an IRkernel)\n",
       "     display(help(display))\n",
       "     ## End(Not run)\n",
       "     "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "display(help(display))  #without display(), help appears in a pager"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To display specific formats, you can use the [`display_<image>`](http://irkernel.github.io/docs/IRdisplay/0.4.4/display_-less-than-image-greater-than.html) and [`display_text`](http://irkernel.github.io/docs/IRdisplay/0.4.4/display_-less-than-text-greater-than.html) functions (their only difference is that images support convenience `width` and `height` arguments):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<h1 style=\"background-color:#fe57a1\">HTML output</h1>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "display_html('<h1 style=\"background-color:#fe57a1\">HTML output</h1>')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Plots are also displayed automatically by the IRkernel, but if you want to display e.&hairsp;g. a PNG from another source, this is how to do it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "image/png": "R0lGODdhAQABAIAAAPxqbAAAACwAAAAAAQABAAACAkQBADsK"
     },
     "metadata": {
      "height": 64,
      "width": 64
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "raw_png_data <- base64enc::base64decode('R0lGODdhAQABAIAAAPxqbAAAACwAAAAAAQABAAACAkQBADsK')\n",
    "display_png(raw_png_data, width = 64, height = 64)\n",
    "#display_png(file = 'a-file.png')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Displaying multiple formats (implicitly or explicitly) allows to choose the frontend to choose the best representation. E.g. when converting to PDF, you’ll want to make sure that `jupyter.plot_mimetypes` contains `image/svg+xml` and/or `application/pdf`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<strong>$jupyter.plot_mimetypes</strong> = <ol class=list-inline>\n",
       "\t<li>'text/plain'</li>\n",
       "\t<li>'image/png'</li>\n",
       "</ol>\n"
      ],
      "text/latex": [
       "\\textbf{\\$jupyter.plot\\_mimetypes} = \\begin{enumerate*}\n",
       "\\item 'text/plain'\n",
       "\\item 'image/png'\n",
       "\\end{enumerate*}\n"
      ],
      "text/markdown": [
       "**$jupyter.plot_mimetypes** = 1. 'text/plain'\n",
       "2. 'image/png'\n",
       "\n",
       "\n"
      ],
      "text/plain": [
       "$jupyter.plot_mimetypes\n",
       "[1] \"text/plain\" \"image/png\" \n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "options('jupyter.plot_mimetypes')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "image/svg+xml": [
       "<svg width=\"10\" height=\"10\"><circle r=\"5\" cx=\"5\" cy=\"5\"/></svg>"
      ],
      "text/plain": [
       "A circle"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "publish_mimebundle(list(\n",
    "    'image/svg+xml' = '<svg width=\"10\" height=\"10\"><circle r=\"5\" cx=\"5\" cy=\"5\"/></svg>',\n",
    "    'text/plain'    = 'A circle'))"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "R",
   "language": "R",
   "name": "ir"
  },
  "language_info": {
   "codemirror_mode": "r",
   "file_extension": ".r",
   "mimetype": "text/x-r-source",
   "name": "R",
   "pygments_lexer": "r",
   "version": "3.3.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}
